1 Audience

I will assume a basic understanding of R Markdown. If you need a refresher or reminder of markdown syntax, see the rmarkdown cheatsheet. This is intended as a brief reference for intermediate to advanced users looking to take their R Markdown game to the next level. Think, a 200 or 300 series course code.

2 Motivation

“Hi, yes, I have a grievance I would like to file:
I signed up to use R, not- yaml, css, js, bib, markdown, and html.”

— Nick Spyrison, 2018. Loosely transcribed.

Suffice it to say that it took and still takes me aggravating amounts of time just to get a new .rmd format compiling, let alone polish options and sizes. I am writing this blog and the corresponding repository to allay such frustrations for my future self and hopefully some others as well.

_... navigate R Markdown output nuances._

… navigate R Markdown output nuances.


I must respond with something slightly cliche, use the right tool for the right job. Problems and tools come in all shapes and sizes. While frustrating at times, these frictions are the right of passage we undergo to achieve a rich diversity and quality of formats. We should also note that they exist for completely valid reasons considering the sometimes nebulous complexity of the moving pieces between code and its output. This document focuses on formats and nuances of using R markdown files (.rmd), which stems primarily from the work of Yihui Xie, many thanks Yihui. I attempt to mitigate friction by providing text and directory examples.

3 R Markdown chunk options

“Hardcoded” content vs generation at compilation:

I recognize this debatably goes against some of the benefits of R markdown. However, if you are a less-than expert level R coder, at least consider the following to minimize frustration and overhead time:

Below I outline some of the more common chunk options and try to explain what they do and list expected values.

For a more lengthy digest consult Yihui’s chapter ‘Options’.

3.1 Intermediate-level chunk options

\```{r setup, include=FALSE}
## Load packages here.
library(knitr)
knitr::opts_chunk$set(
  ###### TEXT DISPLAY:
  echo        = TRUE,     # Echo code executed?
  message     = FALSE,    # Display message text?
  warning     = FALSE,    # Display warning text?
  error       = FALSE,    # Display error text?
  strip.white = TRUE,     # Remove preceeding and trailing line returns from chunks?
  include     = TRUE,     # Include chunk output in compiled document?
  tidy        = FALSE,    # Tidy-up chunk code format?
  ## Expects: FALSE, TRUE=formatR::tidy_source(), "styler"= styler::style_text().
  results     = "hide",   # Chunk results, render formating:
  ## Expectes: "markup"; TeX env, "asis"; in line,
  ##   "hold"; output to the bottom of code, "hide"; no display.
  
  ###### FIGURES AND PLOTS:
  #### Scope: `fig.*` arguments apply to figures produced directly in the .rmd document.
  fig.align   = "center", # Figure alignment. Expects: "left", "right", "center", "default"
  fig.width   = 8,        # Figure width  [in inches, default: 5]
  fig.height  = 5,        # Figure height [in inches, default: 5]
  # fig.asp,  = 1.62      # Figure aspect ratio. do not use with both width and height.
  fig.show    = "hold",   # Figure output formating
  ## Expects "asis"; where generated, "hold"; hold plot display to end of chunk,
  ##   "animate"; wrap all plots into an animation, "hide"; no display.
  fig.pos     = "h",      # "h"olds the postion closer than floating (default: "")
  out.extra   = "",       # Additionally required for fig.pos = "h"
  #### Scope: `out.*` arguments apply to external images (.jpg, .png, .gif) files 
  ####   AS WELL AS, figures produced directly in the .rmd document.
  out.width   = "100%"    # Expects fromats like: "3in", "8cm", "80%", ".8\\linewidth", for HTML: "300px"
  #out.height = "100%",   # Expects fromats like: "3in", "8cm", "80%", ".8\\linewidth", for HTML: "300px"
  ## Try only specifying width or height before applying both.
  
  ###### COMPILING AND SOFT DISPLAY:
  collapse    = TRUE,     # Collapse chunk sections in the .rmd file?
  cache       = FALSE,    # Keep cache files? (default: TRUE)
  ## If output doesn't seem to reflect recent changes, set to FALSE (may also slow compilation time)
  cache.lazy  = FALSE     # Lazily load objects? FALSE is eager loading. (default: TRUE).
  ## If large objects are not behaving, set to FALSE.
)
\```

3.2 chunk options, lite:

\```{r setup_condensed, include=F}
## Load packages here.
library(knitr);
knitr::opts_chunk$set(
  message   = F, warning = F, error = F,
  results   = "asis"                 # Opts: "asis", "markup", "hold", "hide"
  fig.align = "center",              # Opts: "left", "right", "center", "default"
  fig.width = 8, fig.height = 5,
  out.width = "100%"
  fig.pos   = "h", out.extra   = "", # Figures forced closer to chunk location.
  collapse  = TRUE, cache = FALSE, cache.lazy  = FALSE
)
\```

Remember: These same options can be customized for each code chunk

ie. \```{r chunk_name, include=T, cache=F, eval=F, results="markup"}

4 Formal documents and references with pdf_document2

Scope: Static .pdf documents compiled with the bookdown::pdf_document2 format.

Requires:
— in YAML header:

output: bookdown::pdf_document2 ## 'pdf_document2' changes how fig references work to /ref()
bibliography: bib_example.bib   ## Allows bibliography references

— in directory:

./figures/myFigure1.png
./figures/<all other .png, .jpg, .gif files>
./<myBibliographyFile.bib>
A figure caption: _wow, such figure, much caption._

A figure caption: wow, such figure, much caption.

Alternatively in a pdf2_document .rmd file you can define long or complex captions outside of a chunk header:

(ref:thisIsDog-cap) A figure capation made outside of an R chunk arguments. Good for when you do fancy formating or inline \(\LaTeX\) code. Apparently not compatible with ‘html_document’.
(ref:thisIsDog-cap)

(ref:thisIsDog-cap)

5 Dynamic HTML slides with xaringan

Scope: Presentation slides (.html) produced with xaringan::moon_reader.

Requires:
— in YAML:
output: xaringan::moon_reader

5.1 xaringan syntax, ninja style

  • Use — to create a new slide,
    • Provided that it’s followed by any level of # header, which becomes the title of the slide.
  • Bullets: top-level are made with '- ', the space is important.
    • Sub-level bullets need indentation of 4 spaces (2 tabs by default), ie. ' - '.
  • Use -- to create an incremental slide break, hiding later content.
  • Xaringan is very sensitive to white space, make sure to leave plenty of “breathing room”; an empty line before and after almost every bit of content.
  • Xaringan is sensitive to comments; use <!-- <comments> --> sparingly!

5.2 Basic formating and aesthetics with .css files

Scope: Presentation slides (.html) produced with xaringan::moon_reader.

Requires:
— in YAML:

output:
  xaringan::moon_reader:
    css:
       - ninjutsu ### or your next favorite .css file, like: # - "assets/xaringan-themer.css"`
       - "assets/custom.css"

— in directory:

./assets/custom.css
  • Call .css .funtions[], by nesting content inside, with '.functionNm[', and ']' each on their own line:
.pull-left[
Left column content...
]
.pull-right[
...and right column content.
]
  • .pull-left[], .pull-right[] are already defined as general css functions.
  • Create your own .css functions in a .txt file saved as ./assests/custom.css, for instance:
/* Create your own .css functions, like these for changing the size of body text:*/
.larger  {font-size: 120%}
.smaller {font-size: 80% }
  • Examine other .css files to find and look for .{} to develop an idea of what they are trying to do
  • Keep in mind you can nest .css functions:
    • How would you make your text larger than 120%?
    • How would you you make 3 columns of 25%, 25% 50% width?

6 Suggested RStudo settings

Because .yaml headers, xaringan, and some general .rmd formating is so sensitive to the precice number of spaces and line returns:

Because navigating and traversing documents takes too long:

7 Wrap up

Thanks for the read. Let me know if this helped, or if there are other topics you need help getting started with. Drop me a line by email at [](Link text).

8 PS: Code hygiene/formating

A bit off-topic, but it bears repeating. Practice good code hygiene. If you are not yet familiar with this term it doubly applies to you. I suggest reading the Tidyverse Style Guide most of it may seem pedantic, but they are listed for a reason. Not everything will be equally important based on the size of your file, directory, and the number of collaborators, but it’s better to form good habits early.

I strongly, strongly suggest at least:

9 References

Because I have defined a .bib file in my yaml header the items in my .bib file are included below. Note that you do have to define a # References header at the bottom of the .rmd if so desired.

While using pdf_document2 I think only cited refences will be printed rather than all items in the .bib file.

Matejka, Justin, and George Fitzmaurice. 2017. “Same Stats, Different Graphs: Generating Datasets with Varied Appearance and Identical Statistics Through Simulated Annealing.” In Proceedings of the 2017 CHI Conference on Human Factors in Computing Systems - CHI ’17, 1290–4. Denver, Colorado, USA: ACM Press. https://doi.org/10.1145/3025453.3025912.